InitPickMethodProcPtr

InitPickMethodProcPtr
Header:	PictUtils.h		Carbon status:	Supported

Defines a pointer to a method initialization callback function. Your method initialization function specifies the color back and allocates whatever data your color-picking method needs.

typedef OSErr(* InitPickMethodProcPtr) (
    SInt16 colorsRequested, 
    UInt32 *dataRef, 
    SInt16 *colorBankType
);

You would declare your function like this if you were to name it MyInitPickMethodCallback:

OSErr MyInitPickMethodCallback (
    SInt16 colorsRequested, 
    UInt32 *dataRef, 
    SInt16 *colorBankType
);

Parameter descriptions

colorsRequested

The number of colors requested by your application to be gathered for examination in a ColorTable or Palette structure.

dataRef

A handle to any data needed by your color-picking method; that is, if your application allocates and uses additional data, it should return a handle to it in this parameter.

colorBankType

The type of color bank your color-picking method uses. Your MyInitPickMethodCallback function should return one of three valid color bank types.

Return the colorBankIs555 constant in this parameter if you want to let the Picture Utilities gather the colors for a picture or a pixel map into a 5-5-5 histogram. When you return the colorBankIs555 constant, the Picture Utilities call your MyCalcColorTableCallback function with a pointer to the color bank (that is, to the 5-5-5 histogram). Your MyCalcColorTableCallback function selects whatever colors it needs from this color bank. Then the Picture Utilities function called by your application returns these colors in a Palette structure, a ColorTable structure, or both, as requested by your application.

Return the ColorBankIsExactAnd555 constant in this parameter to make the Picture Utilities return exact colors if there are less than 256 unique colors in the picture; otherwise, the Picture Utilities gather the colors for the picture in a 5-5-5 histogram, just as they do when you return the colorBankIs555 constant. If the picture or pixel map has fewer colors than your application requests when it calls a Picture Utilities function, the Picture Utilities function returns all of the colors contained in the color bank. If the picture or pixel map contains more colors than your application requests, the Picture Utilities call your MyCalcColorTableCallback function to select which colors to return.

Return the colorBankIsCustom constant in this parameter if you want to implement your own color bank for storing the colors in a picture or a pixel map. For example, because the 5-5-5 histogram that the Picture Utilities provide gathers colors to a resolution of 5 bits per color, your application may want to create a histogram with a resolution of 8 bits per color. When you return the colorBankIsCustom constant, the Picture Utilities call your MyRecordColorsCallback function to create this color bank. The Picture Utilities also call your MyCalcColorTableCallback function to select colors from this color bank.

function result: A result code. If MyInitPickMethodCallback generates any error, it should return the error as its function result. This error is passed back to the GetPictInfo, GetPixMapInfo, or NewPictInfo function, which in turn passes the error to your application as a function result.

DISCUSSION

Your color-picking method ('cpmt') resource should include a function that specifies its color bank (that is, the structure into which all the colors of a picture, pixel map, or bitmap are gathered) and allocates whatever data your color-picking method needs. Your MyInitPickMethodCallback can let the Picture Utilities generate a color bank consisting of a histogram (that is, frequency counts of each color) to a resolution of 5 bits per color. Or, your MyInitPickMethodCallback function can specify that your application has its own custom color bank—for example, a histogram to a resolution of 8 bits per color.

The 5-5-5 histogram that the Picture Utilities provide if you return the ColorBankIs555 or ColorBankIsExactAnd555 constant in the colorBankType parameter is like a reversed cSpecArray structure, which is an array of ColorSpec structures. This 5-5-5 histogram is an array of 32,768 integers, where the index into the array is the color: 5 bits of red, followed by 5 bits of green, followed by 5 bits of blue. Each entry in the array is the number of colors in the picture that are approximated by the index color for that entry.

For example, suppose there were three instances of the following color in the pixel map:

Red = %1101 1010 1010 1110
Green = %0111 1010 1011 0001
Blue = %0101 1011 0110 1010

This color would be represented by index % 0 11011-01111-01011 (in hexadecimal, $6DEB), and the value in the histogram at this index would be 3, because there are three instances of this color.